将 React 项目从 Webpack 迁移到 Vite 是一个非常实际的升级，能够大幅提升开发启动速度和热更新体验。下面是 从 Webpack 到 Vite 的完整迁移指南（React 版），分为通用步骤 + React 特有部分：

✅ 1. 安装 Vite 和必要插件

卸载 Webpack 相关依赖：

1	npm remove webpack webpack-cli webpack-dev-server

安装 Vite 和 React 插件：

1	npm install vite @vitejs/plugin-react --save-dev

✅ 2. 创建 `vite.config.js`

// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'), // Webpack 的别名替代
    },
  },
  server: {
    port: 3000,
    open: true,
  },
  build: {
    outDir: 'dist',
  },
})

✅ 3. 创建/修改 `index.html`

Vite 以 index.html 为入口，不使用 HtmlWebpackPlugin。你需要自己写：

<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>React + Vite</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>

✅ 4. 修改入口文件

Webpack 可能用 index.js 或 App.js，Vite 推荐用 main.jsx。

// src/main.jsx
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.jsx'
import './index.css'

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
)

✅ 5. 环境变量迁移

Webpack 使用 process.env.NODE_ENV；
Vite 使用 .env 文件，并且变量必须以 VITE_ 开头。

例子：

1 2	# .env VITE_API_BASE=https://api.example.com

使用方式：

1	const api = import.meta.env.VITE_API_BASE

✅ 6. CSS / SCSS 支持

Vite 原生支持 CSS Modules 和 Sass。

你可以在 React 组件中直接这样写：

1	import styles from './App.module.scss'

配置全局 Sass 变量（可选）：

// vite.config.js
css: {
  preprocessorOptions: {
    scss: {
      additionalData: `@import "@/styles/variables.scss";`
    }
  }
}

✅ 7. 别名、资源引用等 Webpack 特性迁移

Webpack 功能	Vite 替代方式
`resolve.alias`	`vite.config.js` 的 `resolve.alias`
`HtmlWebpackPlugin`	直接编辑 `index.html`
`DefinePlugin`	`define` + `.env` + `import.meta.env`
`file-loader`, `url-loader`	直接 `import img from './logo.png'`
Babel	`@vitejs/plugin-react` 内置处理

✅ 8. 修改 `package.json` 脚本

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "serve": "vite preview"
  }
}

✅ 9. 热更新（HMR）

无需配置，Vite 默认支持 React Fast Refresh。

🔁 示例对比：Webpack vs Vite 结构对照

Webpack 文件	Vite 文件
`webpack.config.js`	`vite.config.js`
`public/index.html` 模板	根目录 `index.html`
`src/index.js`	`src/main.jsx`
`process.env.API_URL`	`import.meta.env.VITE_API_URL`

✅ Bonus: 支持 TypeScript?

Vite 完美支持 TS：

1	npm install typescript @types/react @types/react-dom --save-dev

改入口为 main.tsx，组件为 .tsx 即可。

Webpack 是 v4，且依赖老旧。**

这种情况迁移到 Vite 确实更复杂，但也更有意义 —— 因为：

Webpack 4 不支持 ES modules 完整功能，构建较慢
老插件体系（如 extract-text-webpack-plugin、旧版 Babel 配置等）不兼容现代生态
Vite 使用原生 ESM + ESBuild，现代又轻快

✅ 面对旧 Webpack 项目，迁移到 Vite 的关键思路

一、优先评估「旧依赖」是否阻碍迁移

你需要清楚这几个点：

依赖类型	能否直接替代？	注意事项
Babel 7.x 配置	✅ 支持，Vite 用 ESBuild 替代大多数转换
SCSS / Less Loader	✅ Vite 原生支持	`sass`、`less` 要更新版本
`extract-text-webpack-plugin`	❌ 废弃了，用 CSS 自动提取
`file-loader`, `url-loader`	❌ 废弃了，Vite 自动处理
`webpack-dev-server`	✅ 替代为 Vite 内建服务器
`DefinePlugin`	✅ 用 Vite `define` 或 `.env`
`HtmlWebpackPlugin`	✅ 直接使用 HTML 模板

✅ 遇到旧 Webpack 项目时，你可以这样迁移

✅ 1. 把 Webpack 配置文件对照转成 Vite 配置

贴一个旧 Webpack 示例（可能和你类似）：

// webpack.config.js (v4 项目)
const path = require('path')
const HtmlWebpackPlugin = require('html-webpack-plugin')
const webpack = require('webpack')

module.exports = {
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js',
  },
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),
    }
  },
  module: {
    rules: [
      { test: /\.jsx?$/, use: 'babel-loader' },
      { test: /\.scss$/, use: ['style-loader', 'css-loader', 'sass-loader'] },
      { test: /\.(png|jpg|gif)$/, use: 'file-loader' },
    ]
  },
  plugins: [
    new HtmlWebpackPlugin({ template: './public/index.html' }),
    new webpack.DefinePlugin({ 'process.env.NODE_ENV': JSON.stringify('development') })
  ]
}

对应的 Vite 配置如下：

// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src')
    }
  },
  define: {
    'process.env.NODE_ENV': '"development"' // 或使用 import.meta.env
  },
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@import "@/styles/variables.scss";`
      }
    }
  },
  build: {
    outDir: 'dist'
  }
})

✅ 2. 替换不兼容的插件 / loader

Webpack v4 使用	Vite 替代
`babel-loader`	`@vitejs/plugin-react` 内置支持
`style-loader`	Vite 自动注入 CSS
`file-loader`	直接 `import image from './img.png'`
`HtmlWebpackPlugin`	手写 `index.html` 模板

✅ 3. 更新旧依赖（建议性操作）

你可以执行以下操作来清除潜在的 v4 依赖污染：

1 2	rm -rf node_modules package-lock.json npm install

然后迁移这些依赖到 Vite 生态：

1	npm install vite @vitejs/plugin-react sass less --save-dev

❗ 小心事项

1. `process.env`、`global`、`Buffer` 这类 Node API

Vite 是纯浏览器运行，不再默认 polyfill 这些，需要：

1	npm install vite-plugin-node-polyfills --save-dev

2. Babel 配置（如 .babelrc）

Vite 使用 esbuild，速度更快，但如果你用了高级 Babel 插件（如装饰器、class properties），可以保留 .babelrc 并在 vite.config.js 中启用：

react({
  babel: {
    presets: ['@babel/preset-env'],
    plugins: ['@babel/plugin-proposal-class-properties']
  }
})

✅ 总结：Webpack 4 项目迁移 Vite 的路线图

移除旧 Webpack 和相关 loader
安装 vite 和 @vitejs/plugin-react
替代旧配置：手写 index.html，用 alias、define、css 配置替代 Webpack 配置
移除 Babel 配置（或保留兼容处理）
手动检查 polyfill 需求（如 process、Buffer）
重建 package.json 脚本

本文作者：前端analysis

联系邮箱：cheonghu@126.com

← webpack vue迁移到vite 地图canvas和svg选择 →

赏

使用支付宝打赏

使用微信打赏

若你觉得我的文章对你有帮助，欢迎点击上方按钮对我打赏

webpack react迁移到vite